All Databases Inside Mac - Basic Toolbox

NewControl

Create a control, specifying parameters in program

#include <Controls.h> Control Manager

ControlHandle NewControl( theWindow, ctrlRect, title, visible, initialValue,

min, max, ctrlType, refCon );

WindowPtr theWindow ; window in which control should reside

Rect *ctrlRect ; size and location of bounding rectangle

Str255 title ; address of Pascal-style title string

Boolean visible ; TRUE=draw ; FALSE=don't draw

short initialValue ; starting value for control

short min ; minimum control value

short max ; maximum control value

short ctrlType ; indicates control definition procedure

long refCon ; reference constant; caller- defined meaning

returns handle leading to a ControlRecord (or NIL if error)

NewControl allocates memory for and initializes a ControlRecord and

returns a handle leading to the record. The control is inserted into the front of

the window's control list. If visible, the control is drawn immediately.

theWindow is a pointer to a 108-byte GrafPort structure (actually a

156-byte WindowRecord). It identifies the window in which the

control should reside.

ctrlRect is the address of an 8-byte Rect structure. It specifies, in local

coordinates, the position and size of a rectangle enclosing the

entire control. Mouse events occurring within this rectangle are

considered a hit for the control. For a scroll bar, this shape

determines if it is horizontal or vertical.

title is the address of a Pascal-style length-prefixed string

containing any text associated with the control, e.g., the word

inside a button or the text to the right of a check box. If the text

won't fit in ctrlRect, it is truncated.

visible specifies whether or not the control should be drawn initially.

It is one of:

FALSE (0) Don't draw it now

TRUE (1) If ctrlRect is in the visible area of theWindow, then draw the

control.

initialValue specifies the initial setting for controls that maintain such a

value (e.g., dials, scroll bars, etc.). For push buttons, this field

is ignored. For check boxes and radio buttons it specifies the

default setting (0=off, 1=on) i.e., whether it's initially drawn

with an X (or a dot).

min and . . .

max specify the allowed range for the contrlValue field of the

ControlRecord structure. These have no meaning for push

buttons but should be set for all types of dials. For radio buttons

and check boxes, use min =0 and max =1.

ctrlType identifies which type of control you are creating. Part of this

value is the resource ID of the control definition procedure; that

function is read into memory and its handle is stored in the

contrlDefProc field of the ControlRecord structure. The

following standard values are defined in Controls.h:

pushButProc (0) Simple push button

checkBoxProc (1) Check box

radioButProc(2) Radio button

scrollBarProc (16) Scroll bar; arrows, thumb, etc

useWFont (8) When ORed with 0,1, or 2, text is displayed in theWindow 's

current font, style, size and mode rather than the system font.

refCon is any 32-bit long int value. It is stored into the contrlRfCon

field of the ControlRecord structure. It can have any meaning you

wish.

Returns: a ControlHandle; a handle leading to a variable-length ControlRecord

structure. The first 40 bytes are formatted fields, followed by up to

256 bytes of the title .

Notes: NewControl is normally used only while developing an application.

Finished applications use GetNewControl to read control information from

a resource. Most of the parameters can be modified via Control Manager

functions such as SetCTitle, SizeControl, SetCtlValue, and so forth.

Use DisposeControl when you no longer need the control.

The ctrlRect parameter must define a rectangle large enough to hold at

least one character of the title string (if applicable). For scroll bars, the

normal width is 16 pixels wide and at least 48 pixels tall. If smaller, the

scroll bar is scaled to fit. For push buttons, a roundRect is drawn the size

of ctrlRect and the title is centered in it (truncated on both sides, if

necessary).

Note: The Control Manager expects theWindow 's origin to remain at

(0,0). If you use SetOrigin to modify the coordinate system, be sure to

change it back before calling any Control Manager functions.

The ctrlType parameter is composed of two bit- records identifying the

resource from which the control definition procedure is read. It is

formatted as:

For push buttons, radio buttons, and check boxes, the resource ID is 0; for

scroll bars, the resource ID is 1. All of these standard CDEFs can be

obtained directly by using the named constants found in Controls.h (as

above). See Custom Controls for related information.

The control is drawn immediately after this call, not waiting for any

update event to occur. It is initially not highlighted and the default tracking

action occurs (see HiliteControl and SetCtlAction).

The following example creates a standard vertical scroll bar and a

non-standard "Next Window" button near where you might expect to see a

horizontal scroll bar.

Example

#include <Controls.h>

#include <Fonts.h> // used to get constant geneva

ControlHandle c1h, c2h;

Rect r;

WindowPtr theWindow; // assumed to be a document

/* set up theWindow here */

SetPort( theWindow ); // make sure it's the active one

r = theWindow->portRect;

SetRect( &r, r.right-15,r.top-1, r.right+1,r.bottom-14 );

// ------------------- create a scroll bar with a range of 0 to 100

c1h=NewControl( theWindow, &r, "\p", TRUE, 0,0,100, scrollBarProc, 0 );

// --------------- create a push button at the bottom of the window

r = theWindow->portRect;

r.top = r.bottom-14;

r.right = r.left+50;

TextFont( geneva ); TextFace( bold ); TextSize( 10 );

c2h=NewControl( theWindow, &r, "\pNext Window", TRUE,0,0,0,

pushButProc | useWFont, 0);

Referenced by (27):